mcael
 Help information about: InContext Procedure Language
 
 
              E╔════════════════════════════════════════════════╗
              E║          CInContext Procedure LanguageE          ║
              E╚════════════════════════════════════════════════╝


 CA Word to the Wise...

   If you can write MS-DOS batch procedures, you should have no difficulty
   learning to use the InContext Procedure Language.  If "batch files" are
   beyond your present capability, though, then you may want to learn about
   them before you undertake to write your own InContext procedures.  You
   should find the information you need in your MS-DOS User Guide.

   The procedures you write here will usually be based on MS-DOS commands,
   with some notable assistance from a few special commands made available by
   InContext.  Programming, particularly of the "batch file" sort, is really
   not very difficult, and there's no reason to be intimidated by it.  It
   should not be done carelessly, though, since it is possible to
   inadvertently modify, or even delete, files.  Current backups of your
   files can be a real lifesaver, whether you're testing out new procedures
   or not, but they're especially wise in such a case.

   You may find it helpful to F ªPDrint B this information, for easy reference.

 CHow InContext Procedures Work

   A CprocedureB is a list of commands that are executed when:

 ZmcaB       CB an CactionB is selected (see CJ Actions CB).

 ZmcdB       CB an item from the CdoB list is selected (see CJ The Do Command CB).

   The CcommandsB in a procedure consist of some mixture of CMS-DOS commands
   and Cinternal InContext commandsB.  You are assumed to be familiar with the
   common MS-DOS commands, such as "echo", "copy", "move", etc., and we will
   also refer to the invocation of other programs as a use of "MS-DOS
   commands", since they are invoked by asking MS-DOS to execute them. 
   Obviously, though, the InContext commands are unfamiliar, and they will be
   discussed in detail below.

   When a procedure is executed, the commands are executed in sequence,
   starting at the top (except as this may be altered by MS-DOS CgotoB, and
   InContext CmenuB and CforEachObjectB commands).  The internal commands are
   simply executed by InContext when it reaches them.  MS-DOS commands have
   to be passed to the MS-DOS command processor, though.  (Normally, this
   is the program "command.com", but some users substitute an alternative
   command processor.)

   If several consecutive lines of a procedure are MS-DOS commands, they are
   passed to the command processor by writing them out as an MS-DOS batch
   file and arranging for the command interpreter to execute the batch file.
   If an MS-DOS command occurs alone in a procedure, or is surrounded by
   internal commands, it is passed directly to the command processor without
   being written to a batch file.  Since there is some overhead associated
   with invoking the command processor, you can see that CunnecessaryB
   alternation between MS-DOS commands and internal commands would impede
   performance.

   If an error occurs during execution of a procedure, InContext will display
   the error message and halt execution of the procedure.  Please note that
   InContext has no direct way of knowing about errors that may have occurred
   during the execution of other programs (command.com does not return the
   ERRORLEVEL value that is available for testing within batch files).  The
   only errors that can be directly detected by InContext are errors in the
   execution of its internal commands.  For this reason, if for no other, you
   should probably use the CinternalB versions of such commands as copy,
   delete, etc.

 CSwapping InContext Out of Main Memory

   Whenever the MS-DOS command processor is invoked to execute an MS-DOS
   command or another program, part of the InContext program and data are
   "swapped out".  That is, a portion of InContext is written out to either
   EMS memory or to disk, in order to make room for the (possibly large)
   program that is being invoked.  You can control how this swapping occurs,
   and how much memory is freed.  This is done globally by setting the
 ZmcmoeB  appropriate configuration options (see CJ MS-DOS Command Execution CB),
   and locally by the CmemoryB command (see below).

 CA Small Example

   The following example is a little contrived, for which we apologize.  Most
   actions require only a one-line procedure, and we need an example here
   that will illustrate a bit more than those actions would allow.

   Let's suppose that you have a spelling-checker program called "spellit",
   which scans an ASCII text file, noticing words that don't match any entry
   in the program's dictionary.  Assume that the program prompts the user for
   corrections in such a case, and rewrites the file, with spelling
   corrections, on exit.  Let's suppose that it also updates its own
   dictionary if you give it new words during an execution, and that the
   dictionary is kept in the directory "c:\mystuff".  Finally, let's
   assume that spellit requires no more than 256K (256 kilobytes of main
   memory) to run.  If we would like to add a "spell-chk" action for objects
   of the "txt" class.

   An acceptable procedure for such an action might be simply

        spellit %f

   where the characters "%f" will be replaced by the filename of the selected
   text object.  A more complete procedure, though, might be

        !memory 256
        spellit %f
        !relogDir c:\mystuff

   This procedure illustrates the use of both internal commands and MS-DOS
   commands.  The commands preceded by exclamation points (C!B) are internal
   InContext commands.  The first command ("!memory 256") directs InContext
   to swap out only enough of itself to provide 256K of memory for the
   following MS-DOS process.  The second command ("spellit %f") executes
   spellit on the selected object.  The third ("!relogDir c:\mystuff") causes
   InContext to update its record of the contents of the directory
   c:\mystuff, so that it will reflect the modified size, date, etc. of the
   dictionary file.

 CVariable Substitution

   One thing you need to know more about is variable substitution.  During
   the execution of procedures, InContext looks for a set of one-character
   "variable names", each of which is preceded by the percent (C%B) character.
   Whenever one of these variable names is encountered, it is replaced by an
   appropriate value before the command is executed.  For example, if the
   currently selected object is "mystuff.txt", then the command
        myeditor %f
   becomes
        myeditor mystuff.txt
   before it is passed to MS-DOS for execution.

   The InContext variables are:

        C%cB  The CclassB of the currently selected object

        C%dB  The full pathname of the currently selected Cdirectory

        C%DB  The current Cdate

        C%fB  The CfilenameB of the currently selected object

        C%hB  The Cfull pathnameB of the currently selected object

        C%kB  The name of the currently selected CtaskB

        C%KB  The CdescriptionB of the currently selected task

        C%lB  The number of ClinesB currently on the video display

        C%mB  For use only in the group action list, the CmultipleB filespec that
            describes the currently displayed objects.  This might be
            replaced by "*.*", if the "ALL" view is selected, or by "*.txt",
            if only the text class is selected, or by "*.doc *.txt" if a view
            containing both "doc" and "txt" classes is selected.

        C%pB  The filename CprefixB of the currently selected object

        C%TB  The current Ctime

        C%uB  The name of the current CuserB of InContext

   The following additional variables are related to the "query" command.

        C%1B  The current value of variable 1
        C%2B  The current value of variable 2
        C%3B  The current value of variable 3
        C%4B  The current value of variable 4
        C%5B  The current value of variable 5
        C%6B  The current value of variable 6
        C%7B  The current value of variable 7
        C%8B  The current value of variable 8
        C%9B  The current value of variable 9

   The following additional variables have meaning only when executing a
   "forEachObject" loop:

        C%CB  The class of the current object
        C%FB  The filename of the current object
        C%HB  The full pathname of the current object
        C%PB  The filename prefix of the current object

 CMacros

   The use of Macros is common in programming languages at all levels, and
   it can greatly increase power and reuseability of procedures.  For
 ZmcaemB   information, see CJ Macro Action Definitions CB),

   Macros in procedures are indicated by the use of the pound sign (C#B) as the
   first character of the line.  Thus, a common way of invoking the user's
   preferred text editor is
      #editText
   where the "editText" macro contains the detailed command(s) necessary
   to invoke the editor in the desired manner.

 CInContext Internal Commands

   The internal commands are listed below, along with descriptions and, where
   appropriate, examples.  For any commands that take arguments, the syntax
   of the command is also shown.  In syntax descriptions, everything shown
   in CboldB text must appear as shown, while everything shown in ordinary
   text is a placeholder.  Optional information is surrounded by square
   brackets.  Thus, the description:
        CdeleteB [ filename ] [ CnoqueryB ]
   indicates that the delete command takes two optional arguments, one of
   which is a filename and the other of which is the string "noquery".

   The internal commands you would ordinarily use are:
                        
        CchangeDirB       This command changes the current working
                        directory to a specified directory.  The chosen
                        directory will remain the current working directory
                        until the next "changeDir" command, or the next
                        MS-DOS "cd" command, or the end of the procedure.
                        This command is equivalent to the MS-DOS "cd" command
                        except that it can cause a change in drive, as well
                        as directory.  Syntax is:
                           CchangeDirB pathOfNewDir
                        Thus, to change to the "temp" directory on the "d:"
                        drive, the command would be
                           changeDir d:\temp
                        Use of this command is preferable to the MS-DOS "cd"
                        command, because InContext will be aware of the
                        working directory, and will therefore automatically
                        relog the directory.

        CchoiceB          See "menu".

        CcopyB            This command exhibits two different kinds of
                        behavior, depending on the arguments used.
                        Syntax is:
                           CcopyB [ source destination [ CnoqueryB ] ]
                        If no arguments are used, as in
                           copy
                        the command prompts the user for the name (or
                        possibly directory or full path) to which the
                        selected object should be copied.  If the user
                        responds with such a name or path, the copy operation
                        is executed.

                        Alternatively, if source and destination pathnames
                        are given, the indicated source file is copied to
                        the indicated destination.  The source must indicate
                        an existing file, and may be a simple filename, if
                        the file is in the current directory, or a complete
                        pathname.  The destination can be a simple filename
                        or a full pathname.  If the destination is found to
                        be a directory, a new copy of the source will be
                        placed in the destination directory, using the source
                        filename.  Otherwise, a new copy of the source file
                        will be created and given the destination filename.

                        If there is already a file using the destination
                        name, the user will be asked for permission before
                        copying occurs, unless the "noquery" argument is
                        present.  Thus, the command
                           copy myfile.txt a:\ noquery
                        would copy "myfile.txt" to the root directory of the
                        A: drive, and would not ask permission before over-
                        writing a file of the same name there.

        CcreateObjectB    This command creates a new object, based on the
                        filename prefix and class specified in the command.
                        Syntax is:
                           CcreateObjectB prefix class
                        Thus, the command "createObject mynext doc" would
                        create the object "mynext.doc" in the current
                        directory.

        CdeleteB          This command deletes the specified object, or if
                        none is specified, deletes the currently selected
                        object.  The user is asked for permission before
                        deletion, unless "noquery" is specified.  Syntax is:
                           CdeleteB [ filename ] [ CnoqueryB ]
                        Thus, to delete the file "mytemp.txt", without asking
                        user permission, the command would be
                           delete mytemp.txt noquery
                        If the file does not exist, no deletion occurs and
                        no error is noted.

        CeditB            This command invokes the internal editor on the
                        specified file, if any, or on the currently selected
                        object, if no file was specified.  Syntax is:
                           CeditB [ filename ]

        CeditDictionaryB  Some of the files used by InContext are
                        "dictionary" files (class "dic").  The internal
                        dictionary editor is made available for use on such
                        objects by this command.  You might use this command
                        to create dictionary files for use with the "info"
                        command (see below).  Syntax is:
                           CeditDictionaryB [ filename ]

        CendForB          See "forEachObject".

        CendMenuB         See "menu".

        CforEachObjectB   This command allows you to execute a portion of
                        a procedure once for each object currently being
                        displayed.  You might use it if you have a program
                        that only operates on one file at a time, but you
                        want to be able to invoke it on a whole class or
                        view.  If the program is question is "theprog", the
                        commands required would be:

                           !forEachObject
                              theprog %F
                           !endFor

                        Notice that the "endFor" command is also required,
                        and that it indicates the end of the loop that will
                        be executed once for each object.  Notice also that
                        the special variable names %F, %H, %C, and %P must be
                        used instead of %f, %h, %c, and %p.

        CinfoB            This command allows you to display a scrollable
                        window containing text you have written.  It is
                        useful for providing explanations of a procedure
                        during its execution.  Syntax is:
                           CinfoB dictionaryPath term [ title ]
                        The information displayed will be the definition of
                        the specified term, taken from the dictionary ("dic"
                        object) whose full MS-DOS pathname is specified.
                        If you provide a title, that title will be displayed,
                        as well.  For example, to display information at the
                        beginning of a Do procedure that downloads stock
                        prices, you might use the command:
                           info c:\incontxt\myinfo.dic getprice

        CkeyStuffB        This command allows you to place information in the
                        keyboard buffer before calling an application. 
                        Suppose, for example, you have a word processor that
                        doesn't allow you to specify a filename on the
                        command line, but expects you to select a "file load"
                        command after you're in the program.  You might use a
                        command sequence like:

                             !keyStuff "FL%f\EN"
                             myWordProc

                        to cause it to automatically load the selected object
                        upon entry.  The !keyStuff command loads the keyboard
                        buffer with the command characters 'F' and 'L',
                        followed by the filename of the currently selected
                        object, followed by the ENTER key.  Those characters
                        will then be read by the program "myWordProc" as if
                        they had been typed from the keyboard after the
                        program was invoked.  This will not work with ALL
                        programs, but works with most.  This feature greatly
                        increases your ability to "encapsulate" applications
                        with InContext.

                        There are a number of special characters that can be
                        loaded into the keyboard buffer using this technique.
                        An example is the ENTER key designated by the "\EN"
                        in the example above.  These special characters are
                        all indicated by a backslash and a two-character code
                        that represents the special character.  The codes are
                        as follows:

                             For Cfunction keysB, the code consists of the
                             character "F", followed by a numeric digit from
                             1 through 0.  These correspond to function keys
                             F1 through F10.  "\FA" also means F10, and
                             "FB" and "FC" correspond to F11 and F12 on the
                             extended keyboard.  (The hexadecimal symbols for
                             10, 11, and 12 are A, B, and C, respectively.)

                             If Cshifted function keysB are desired, the codes
                             are "\S1" through "\S0" and "\SA" through "\SC".
                             CControl-function-keyB combinations are obtained
                             by "\C1" through "C0" and "\CA" through "\CC".
                             CAlt-function-keyB combinations are "\A1" through
                             "\A0" and "\AA" through "\AC".

                             Ordinary Ccontrol charactersB, such as control-A,
                             use codes beginning with '^'.  Thus, "\^A"
                             through "\^Z" mean control-A through control-Z,
                             and control-key versions of the following
                             additional characters can be created this way:
                                  [ \ ] ^ _ @

                             Ordinary Calt-key charactersB, such as alt-A,
                             use codes beginning with '@'.  Thus, "\@A"
                             through "\@Z" mean alt-A through alt-Z,
                             and alt-key versions of the following
                             additional characters can be created this way:
                                  numeric digits, -, =

                             All remaining Cspecial charactersB are shown in
                             the following table:
                                  LA    left arrow
                                  LC    control left arrow
                                  RA    right arrow
                                  RC    control right arrow
                                  UA    up arrow
                                  UC    control up arrow
                                  DA    down arrow
                                  DC    control down arrow
                                  HM    home
                                  HC    control home
                                  ED    end
                                  EC    control end
                                  PU    page up
                                  QU    control page up
                                  PD    page down
                                  QD    control page down
                                  IN    insert
                                  DE    delete
                                  G+    grey +
                                  G-    grey -
                                  G*    grey *
                                  PS    PrtSc
                                  PC    control PrtSc
                                  TA    tab
                                  BT    back tab
                                  ES    escape
                                  BS    back space
                                  EN    ENTER (carriage return)
                                  LF    line feed
                                  N0    numeric key-pad 0
                                  N1    numeric key-pad 1
                                  N2    numeric key-pad 2
                                  N3    numeric key-pad 3
                                  N4    numeric key-pad 4
                                  N5    numeric key-pad 5
                                  N6    numeric key-pad 6
                                  N7    numeric key-pad 7
                                  N8    numeric key-pad 8
                                  N9    numeric key-pad 9
                                  N.    numeric key-pad .
                                  N+    numeric key-pad +
                                  N-    numeric key-pad -
                                  N*    numeric key-pad *

                        To stuff the backslash character into the buffer, use
                        two backslashes in succession, as "\\".

                        In the current version of InContext, the string that
                        is loaded by "!keyStuff" is restricted to 15
                        characters.  This will be extended in a later
                        version.

                        Incidentally, whenever InContext executes another
                        program, it clears the keyboard buffer on return.
                        This prevents unprocessed keystrokes from doing
                        unexpected things upon return to InContext.  However,
                        if the "!keyStuff" command is used and not followed
                        by the execution of another program, the keystrokes
                        are left in the buffer and read by InContext as if
                        you had typed them in yourself.  This allows you to
                        define procedures that exert user-level control over
                        InContext, if you like.  This is recommended for
                        knowledgable users only.

                        An especially useful application of the latter is in
                        an InContext startup ("incStart") macro.  By placing
                        in that macro, for example,
                           !keyStuff "df"
                        it is possible to cause the automatic execution of
                        a Do procedure (e.g., "fontset") at InContext
                        initialization time.

        CmemoryB          This command allows you to specify the amount of
                        memory needed for the next following block of MS-DOS
                        commands.  You can optimize InContext performance by
                        requesting only what is actually needed, if you
                        choose to do so.  Syntax is:
                           CmemoryB kilobytes
                        Thus, to invoke a simple word-count program that
                        needs only 64K of memory, you might use the commands
                           !memory 64
                           wc %f

        CmenuB            This command allows you to construct menus within
                        a procedure.  Syntax is:
                           CmenuB [ title ]
                        This command is used with a series of "choice"
                        commands and an "endMenu" command, to specify a whole
                        menu and the consequences of each possible choice.
                        A simple example is:

                           !menu "Do which simple MS-DOS operation?"
                              !choice "Check disk"
                                 chkdsk
                              !choice "Show directory contents"
                                 dir
                           !endMenu

                        Menus may not be nested (but notice that that
                        probably isn't necessary, given that the menus occur
                        in the context of actions that are themselves menu-
                        selected).

        CnoRelogB         This command can be used to slightly speed up
                        the return of InContext after a procedure, if you
                        know that the procedure cannot alter any files.
                        By letting InContext know that the files cannot be
                        altered, you eliminate the need for relogging the
                        files in the current directory upon return from the
                        procedure.  This command can occur anywhere in the
                        procedure.  A common example would be the use of a
                        viewer:
                           !noRelog
                           pcxview %f

        CpauseB           This command causes InContext to pause, and wait
                        for a keystroke or mouse key depression.  It is used
                        immediately after a DOS command or external program
                        in order to allow the user to look at the results of
                        that operation before returning to InContext.

        CqueryB           This command allows you to ask the user for
                        information, and then to use the information in
                        subsequent commands in the procedure.  Syntax is:
                           CqueryB variable question length
                        InContext provides nine variables whose values can
                        be set by query commands.  The first argument is the
                        number of the variable that will contain the user's
                        answer.  The second argument is the text of a
                        question that will be asked.  The third argument is
                        the length, in characters, of the answer field.
                        At the risk of waxing a little fanciful, suppose you
                        have a program, "coatarms" that displays a coat of
                        arms for the user's family, given his family name.
                        You might write:
                           !query 3 "Enter your last name" 20
                           coatarms %3
                        If the user answers "Smith", this would result in
                        the actual execution of the command "coatarms Smith".

        CrelogDirB        Unless you use the "noRelog" command, InContext
                        always checks all the files in the current directory
                        at the end of each procedure, to make sure that its
                        object list is up-do-date.  It does CnotB automatically
                        relog other directories, however.  If you execute a
                        program that is known to modify the contents of some
                        other directory, you can cause InContext to update
                        the log for that directory as well, by use of the
                        "relogDir" command.  Syntax is:
                           CrelogDirB pathOfDirectory
                        For example, if your editor automatically backs up
                        all files to the directory "c:\backup", and you want
                        the object list to be current whenever you go to that
                        directory, you might use the sequence
                           myeditor %f
                           !relogDir c:\backup
                        to invoke your editor.

        CrenameB          This command exhibits two different kinds of
                        behavior, depending on the arguments used.
                        Syntax is:
                           CrenameB [ source destination [ CnoqueryB ] ]
                        If no arguments are used, as in
                           rename
                        the command prompts the user for the new name for
                        the selected object.  This may be a simple filename
                        or a full pathname (this command can be used to move
                        the selected object to another directory, or even
                        another drive).  If the user responds with such a
                        name, the object is moved and/or renamed, as
                        appropriate.

                        Alternatively, if source and destination pathnames
                        are given, the indicated source file is moved to
                        the indicated destination.  The source must indicate
                        an existing file, and may be a simple filename, if
                        the file is in the current directory, or a complete
                        pathname.  The destination can be a simple filename
                        or a full pathname.  If the destination is found to
                        be a directory, the source object will be placed in
                        the destination directory, using the source filename.
                        Otherwise, the source object will be given the
                        destination filename, and moved to the indicated
                        drive or directory if that information was included
                        in the destination.

                        If there is already a file using the destination
                        name, the user will be asked for permission before
                        renaming occurs, unless the "noquery" argument is
                        present.  Thus, the command
                           rename myfile.txt a:\ noquery
                        would move "myfile.txt" to the root directory of the
                        A: drive, and would not ask permission before over-
                        writing a file of the same name there.

        CresetMouseB      Some programs which you may invoke from within
                        InContext disable the mouse and fail to restore it
                        upon exit.  If you don't see a cursor upon return
                        from such a program, or if the mouse no longer works,
                        you should add the "resetMouse" command to the
                        procedure.  On some machines, the mouse reset
                        operation adds a second or two to the time required
                        to return to InContext; that's why it isn't done
                        every time.

        CunloadB          A few memory-hungry applications may require more
                        memory for their execution than InContext can make
                        available by swapping itself to disk or EMS.  A good
                        example is Ventura Publisher, if run on a machine
                        that doesn't have EMS memory.  The "unload" command
                        can be used to cause InContext to write out the
                        desired MS-DOS commands to a batch file, and then
                        Cquit altogetherB, freeing CallB of the memory
                        used by InContext.  Since the batch file is still
                        there, it can be executed from DOS.

                        When you installed InContext, you installed a batch
                        file, "inc.bat", which is used to execute InContext.
                        "inc.bat" checks, after each invocation of InContext,
                        to see if a procedure batch file has been left behind
                        for execution.  If so, that batch file is executed
                        and InContext is reloaded.

                        You will only want to "unload" InContext in those few
                        cases that really need it, for performance reasons.
                        Note that, when "unload" is used, only the block of
                        MS-DOS commands immediately CfollowingB "unload" can
                        be executed.  If you have any additional internal
                        commands after that block, they will not be executed.

        CverifyB          This command asks the user if it's OK to proceed,
                        and terminates the procedure if the user fails to
                        answer "Yes".  Syntax is:
                           CverifyB [ question ]
                        If a question is specified, it is asked instead of
                        the default question.  Thus, a possible form of this
                        command is
                           verify "Is it OK to archive this file?"

        CviewB            This command invokes the internal viewer on the
                        specified file, if any, or on the currently selected
                        object, if no file was specified.  Syntax is:
                           CviewB [ filename ]

        CviewArchiveB     This command invokes the internal archive viewer
                        on the specified file, if any, or on the currently
                        selected object, if no file was specified.  Syntax is:
                           CviewArchiveB type [ filename ]

                        The "type" argument can be any of the following, and
                        specifies both the archive file format and the
                        archiver program(s) to be used:

                           CACAB  ARC format, using ARCA/ARCE.

                           CARCB  ARC format, using SEA's ARC.

                           CARJB  ARJ format, using ARJ.

                           CLZHB  LZH format, using LHA.

                           CPAKB  PAK format, using PAK.

                           CPKPB  ARC format, using PKPAK/PKUNPAK

                           CZIPB  ZIP format, using PKZIP/PKUNZIP.

                        For example, the following command would invoke the
                        archive viewer on an ARC-type document archive called
                        DOC-ARCV.XYZ, using the PKPAK/PKUNPAK programs for
								any archive operations:

                           viewArchive PKP doc-arcv.xyz
                       
        CviewLZHB         This command invokes the internal LHA viewer
                        on the specified file, if any, or on the currently
                        selected object, if no file was specified.  Syntax is:
                           CviewLZHB [ filename ]

                        This command is now obsolete, and will not be
                        supported in future versions.  Use "viewArchive LZH",
                        instead.

   The following commands are also available, but you will ordinarily have
   no need to use them in your own procedures:

        CdeleteDirB       If the current directory is empty and is not the
                        root directory of its drive, this command deletes the
                        directory and moves to the next directory above it.

        CdeleteGroupB     This command checks with the user first, and then
                        deletes each currently displayed object.  Depending
                        on the user's choice, the objects can be deleted or
                        saved individually, or deleted as a group in a single
                        operation, or the command can be aborted.

        CputB             This command drops either a copy or the original
                        of an object being "carried" into the current
                        directory.  The user is asked which is preferred.
                        This command is really only intended for internal
                        InContext use.

        CtakeB            This command causes InContext to "pick up" the
                        selected object, for possible later copying or moving
                        via the "put" command, above.

